From 25b90907ad5a663b06eb73b8dc5a338e714bc1c2 Mon Sep 17 00:00:00 2001
From: Matthias Clasen <mclasen@redhat.com>
Date: Mon, 9 Mar 2020 13:46:42 -0700
Subject: [PATCH] surface: document gdk_surface_translate_coordinates

---
 gdk/gdksurface.c | 18 ++++++++++++++++++
 1 file changed, 18 insertions(+)

diff --git a/gdk/gdksurface.c b/gdk/gdksurface.c
index 63665e1877..a8621716f2 100644
--- a/gdk/gdksurface.c
+++ b/gdk/gdksurface.c
@@ -2962,6 +2962,24 @@ gdk_surface_handle_event (GdkEvent *event)
   return handled;
 }
 
+/**
+ * gdk_surface_translate_coordinates:
+ * @from: the origin surface
+ * @to: the target surface
+ * @x: coordinates to translate
+ * @y: coordinates to translate
+ *
+ * Translates the given coordinates from being
+ * relative to the @from surface to being relative
+ * to the @to surface.
+ *
+ * Note that this only works if @to and @from are
+ * popups or transient-for to the same toplevel
+ * (directly or indirectly).
+ *
+ * Returns: %TRUE if the coordinates were successfully
+ *     translated
+ */
 gboolean
 gdk_surface_translate_coordinates (GdkSurface *from,
                                    GdkSurface *to,
-- 
2.30.2